package vfs.persist.entity.manage;

import vfs.filter.VFSFilter;
import vfs.obj.entity.VFSEntity;
import java.util.Iterator;
import java.util.Map;
import vfs.except.VFSCreationException;
import vfs.except.VFSModificationException;


/**
 * VFSEntityManager handles the addition, update, retrieval, and removal of
 * a particular type of entity in the storage medium.
 *
 * @author Matthew Eavenson <durandal@uga.edu>
 */
public interface VFSEntityManager<T extends VFSEntity> {
    
    /**
     * Adds an entity of type T to the storage medium.
     * 
     * @param obj the object to be added
     */
    void add(T obj);
    
    /**
     * Adds an entity of type T to the storage medium.  This 
     * method also takes a map of foreign key ids which is
     * sometimes necessary for initial creation.
     * 
     * @param obj the object to be added
     * @param foreignKeys a map of foreign key ids
     */
    void add(T obj, Map<String,String> foreignKeys);
    
    /**
     * Updates an entity of type T in the storage medium.
     * The entity's fields are updated according to any
     * changes made to the object since it was restored
     * from the storage medium.
     * 
     * @param obj the object to be updated
     */
    void update(T obj);
    
    /**
     * Retrieves an entity of type T from the storage medium
     * based on its primary key id.
     * 
     * @param id the primary key of the entity
     * @return the entity with the given id if it exists, null otherwise
     */
    T get(long id);
    
    /**
     * Retrieves multiple entities of type T from the storage medium
     * based on a filter.
     * 
     * @param filter the filter applied to the retrieval
     * @return an iterator over all entities matching the given filter
     */
    Iterator<T> get(VFSFilter filter);
    
    /**
     * Removes an entity of type T from the storage medium.
     * 
     * @param obj the object to be removed
     */
    void remove(T obj);
    
    /**
     * Removes an entity of type T from the storage medium
     * based on its primary key id.
     * 
     * @param id the id of the object to be removed
     */
    void remove(long id);
    
    /**
     * Removes multiple entities of type T from the storage medium
     * based on a filter.
     * 
     * @param filter the filter applied to the removal
     */
    void remove(VFSFilter filter);
        
}
